##############################################################################
###+----------+###############################################################
#+-| F_OPEN() |-------------------------------------+#########################
#| +----------+ Opens a file specified by file_name |#########################
#+--------------------------------------------------+#########################
##############################################################################
##############################################################################
#+--| Summary |----------------+##############################################
#|     #INCLUDE fileio.hdr     |##############################################
#+-----------------------------+##############################################
##############################################################################
##############################################################################
#+--| Syntax |--------------------------------------------------+#############
#|     FUNCTION LOGICAL f_open PROTOTYPE                        |#############
#|      PARAMETERS FILE file_stream, CONST CHAR file_name,;     |#############
#|      VALUE INT file_mode                                     |#############
#+--------------------------------------------------------------+#############
##############################################################################
##############################################################################
#####+---| Description |------------------------------------------------+#####
#####| The f_open() function opens a file specified by file_name and    |#####
#####| associates the file with file_stream.  The file_mode establishes |#####
#####| access to the file - either read only, create or append.  The    |#####
#####| file is assumed to be ASCII, with lines terminating in carriage  |#####
#####| return, line feed characters.                                    |#####
#####| ---------------------------------------------------------------- |#####
#####| Upon opening, the DOS read/write pointer is positioned at the    |#####
#####| first character of the file.  If the file is opened as read only |#####
#####| then the f_put or f_putln procedures have no effect on the file. |#####
#####| f_open() uses a DOS file handle for the file.                    |#####
#####| ---------------------------------------------------------------- |#####
#####| FORCE library supports up to 255 open files at one time.  Use    |#####
#####| more_handles to allocate DOS file handles.                       |#####
#####| ---------------------------------------------------------------- |#####
#####| Defines for the opening modes are predefined in the fileio.hdr   |#####
#####| file.  The BUFFERED FILE I/O OPEN TABLE summarizes the defines   |#####
#####| and the open modes.                                              |#####
#####+------------------------------------------------------------------+#####
##############################################################################
##############################################################################
#########+--| Example 1 |-------------------------------------------+#########
#########| *    Open a file for appending (i.e., the lines are      |#########
#########| *    added to the end of the file).  Create the file     |#########
#########| *    if it does not exist.                               |#########
#########|                                                          |#########
#########|     IF .NOT. f_open( a, f[0], &F_APPEND )                |#########
#########|         IF .NOT. f_open( a, f[10], &F_CREATE )           |#########
#########|             ? "Unable to create file"                    |#########
#########|         ENDIF                                            |#########
#########|     ENDIF                                                |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 2 |-------------------------------------------+#########
#########| *    Append a file to a memo field and return .T.        |#########
#########| *    if it worked, .F. if it failed.                     |#########
#########|                                                          |#########
#########| FUNCTION LOGICAL append_memo                             |#########
#########|  PARAMETERS MEMO memo_field, CONST CHAR disk_name        |#########
#########|                                                          |#########
#########|     VARDEF                                               |#########
#########|         FILE    disk_file                                |#########
#########|         CHAR    line                                     |#########
#########|     ENDDEF                                               |#########
#########|                                                          |#########
#########| *--- open the disk file for read only                    |#########
#########|                                                          |#########
#########|     IF .NOT. f_open (disk_file, disk_name, &F_READ )     |#########
#########|         RETURN .F.                                       |#########
#########|     ENDIF                                                |#########
#########|                                                          |#########
#########| *--- open the memo field for appending                   |#########
#########|                                                          |#########
#########|     m_open(memo_field, &MO_APPEND )                      |#########
#########|                                                          |#########
#########| *--- read a line from the disk file and then             |#########
#########| *    write it to the memo                                |#########
#########|                                                          |#########
#########|     DO WHILE .NOT. f_eof( disk_file )                    |#########
#########|         f_getln( disk_file, line )                       |#########
#########|         m_put( memo_field, line )                        |#########
#########|     ENDDO                                                |#########
#########|                                                          |#########
#########| *--- close the file and the memo                         |#########
#########|                                                          |#########
#########|     f_close( disk_file )                                 |#########
#########|     m_close( memo_field )                                |#########
#########|     RETURN .T.                                           |#########
#########|                                                          |#########
#########| ENDPRO                                                   |#########
#########+----------------------------------------------------------+#########
##############################################################################